TVicHw32 version 1.1 Copyright (C) 1997 Victor Ishikeev Portions Copyright (C) 1997 EnTech Taiwan e-mail: tools@entechtaiwan.com README CONTENTS ======== 1. OVERVIEW 2. REGISTRATION 3. INSTALLATION 4. GENERAL TVicHW32 COMPONENT PROPERTIES AND METHODS 5. DIRECT MEMORY ACCESS WITH TVicHW32 6. DIRECT PORT I/O WITH TVicHW32 7. HARDWARE INTERRUPT HANDLING WITH TVicHW32 8. CONTACT INFORMATION 1. OVERVIEW =========== TVicHW32 is a shareware component for use with Delphi 2.0 which allows you to control hardware from a Win32 application without using the Windows DDK. TVicHW32 provides transparent support for Windows 95 and Windows NT, providing Delphi programmers with a standard method for real-time direct access to port I/O, memory I/O, and hardware interrupts - without requiring you to write a custom virtual device driver for Windows 95 or a kernel-mode driver for NT. Evaluation copies of the TVicHW32 component consist of the following elements: - vichw00.vxd and vichw00.sys evaluation run-time kernel mode drivers, which manage all port and memory I/0, and interrupt handling - hw_32.dcu and loadhw.dcu Delphi interface units to the kernel mode drivers - hw_test.dpr and main.* Sample program, with source, demonstrating some of the features of the TVicHW32 component 2. REGISTRATION =============== TVicHW32 is shareware. You must read and accept the terms detailed in the license.txt file before you can use this component. An order form is provided in the file order.txt for the purpose of registering this component. Registered users will receive: - vichw11.vxd and vichw11.sys royalty-free run-time kernel mode drivers, which manage all port and memory I/0, and interrupt handling - hw_32.pas and loadhw.pas Delphi interface source code to the kernel mode drivers TVicHW32 is maintained at the following internet address: http://www.entechtaiwan.com/tools.htm e-mail: tools@entechtaiwan.com where you can find the latest release and links to support and on-line ordering sites. 3. INSTALLATION =============== TVicHW32 is installed on the "Drivers" page of the VCL palette, by following the steps below: 1) Create a directory for the TVicHW32 component, e.g., C:\HW 2) For use with Windows 95, copy the vichwXX.vxd file to your Windows 95 system directory, e.g., C:\WINDOWS\SYSTEM 3) For use with Windows NT, copy the vichwXX.sys file to your Windows NT drivers directory, e.g., C:\WINDOWS\SYSTEM32\DRIVERS 4) Add the TVicHW32 component to your Delphi component library by selecting Component|Install|Add... and then click Ok to rebuild the library 4. GENERAL TVicHW32 COMPONENT PROPERTIES AND METHODS ==================================================== After successfully adding the TVicHW32 component to your VCL, and after copying the kernel-mode driver(s) to the appropriate Windows directories, you can test the functionality of the component, and examine the sample code provided, by opening the included HW_TEST demonstration program. TVicHW32 has the following general component properties and methods: constructor Create (Owner: TComponent); override; ------------------------------------------------- The Create method allocates memory to create the TVicHW32 component and initializes data as needed. Note that Create does *not* automatically open the kernel-mode driver: you must open the kernel-mode driver with the OpenDriver method (see below). You do not normally need to directly call the Create method; the component is automatically created at run-time. destructor Destroy; override; ----------------------------- The Destroy method destroys the TVicHW32 component releases the memory allocated to it. If a hardware interrupt was "unmasked" to permit direct access, the "mask" is automatically restored, and if the kernel-mode driver was opened, it is automatically closed. You do not normally need to directly call the Destroy method; the component is automatically destroyed when the application closes. procedure OpenDriver; --------------------- Loads the vichwXX.vxd (under Windows 95) or vichwXX.sys (under Windows NT) kernel-mode driver, providing direct access to the hardware. If the kernel-mode driver was successfully opened, the boolean ActiveHW property (see below) will be set to True; if the procedure fails, the ActiveHW property will be False. procedure CloseDriver; ---------------------- Closes the kernel-mode driver and releases memory allocated to it. If a hardware interrupt was "unmasked", the "mask" is restored. If the driver was successfully closed, the ActiveHW property (see below) will be set to False. property ActiveHW: Boolean; (published, read); ---------------------------------------------- The read-only and run-time ActiveHW property specifies whether the kernel-mode driver is open. ActiveHW returns True if the driver is open, or False if it is not. 5. DIRECT MEMORY ACCESS WITH TVicHW32 ===================================== The following function permits direct memory acccess: function MapPhysToLinear (PhAddr: dWord; Size: dWord): Pointer; ---------------------------------------- ---------------------- Maps a specific physical address to a pointer in linear memory, where PhAddr is the base address and Size is the actual number of bytes to which access is required. Note that a subsequent call to MapPhysToLinear invalidates the previous pointer. The following example returns a pointer to the system ROM BIOS area: type TBiosArray = array [0 ..255] of Byte; PBiosArray = ^TBiosArray; var pBIOS: PBiosArray; begin with VicHw32 do begin OpenDriver; if ActiveHW then begin PBIOS:=MapPhysToLinear ($F8000,256) // 255 bytes beginning at $F8000 {...working with pBIOS...} CloseDriver; end else ShowMessage('ERROR: Kernel-mode driver is not open.'); end; end; 6. DIRECT PORT I/O WITH TVicHW32 ================================ For access to the 80x86 CPU data ports, TVicHW32 provides an implementation of the traditional Borland Pascal 7 predefined arrays, Port and PortW, and adds PortL (which accepts a DWORD) and a "Hard/Soft" boolean switch. When a value is assigned to an array of type Port, PortW, or PortL, the value is output to the selected port. When an array of type Port, PortW or PortL is referenced in an expression, its value is input from the selected port. Use of the Port, PortW and PortL arrays are restricted to assignment and reference in expressions only. The following properties permit direct I/O port access: property Port[Index: Word]: Byte; (public, read, write); -------------------------------------------------------- Value of the Port array is of type Byte. property PortW [Index: Word]: Word; (public, read, write); --------------------------------------- ------------------ Value of the PortW array is of type Word. property PortL [Index: Word]: dWord; (public, read, write); --------------------------------------- ------------------- Value of the PortL array is of type DWord. property HardAccess: Boolean; (published, read, write); --------------------------------------- --------------- The HardAccess property determines whether the kernel-mode driver should use "hard" or "soft" access to the I/O ports. If set to True "hard" access is employed; if set to False "soft" access is employed. "Soft" access provides higher performance access to ports, but may fail if the port(s) addressed are already in use by another kernel-mode driver. While slower, "Hard" access provides more reliable access to ports which have already been opened by another kernel-mode driver. The following example demonstrates direct port I/O calls, and generally complies with traditional Borland Pascal 7 syntax to facilitate porting 16-bit code to Delphi 2: with VicHw32 do begin {...} Port[$2F8]:=$34; // write a byte to port {...} MyByte:=Port[$2f9]; // read a byte from a port {...} end; 7. HARDWARE INTERRUPT HANDLING WITH TVicHW32 ============================================ In a Win32 environment, hardware interrupts are normally hidden or "masked" by Windows; the TVicHW32 kernel-mode driver allows you to "unmask" the interrupt for direct handling by your application. Note that only one interrupt can be handled at a time. The following properties and methods permit access to hardware interrupts. property OnHwInterrupt: TNotifyEvent; published; ------------------------------------------------ Notification event that a specific hardware interrupt has occurred. property IRQNumber: Byte; (published, read, write) -------------------------------------------------- Specifies which hardware interrupt (IRQ1..15) is to be unmasked for processing. Note that IRQ0 (the system timer) is *not* supported. procedure SetIRQ; ----------------- Assign the interrupt specified by the IRQNumber property to the OnHwInterrrupt event, and sets the IsIRQSet property (see below) to True. procedure UnmaskInterrupt; -------------------------- Unmasks the hardware interrupt specified by the IRQNumber property, so that an OnHWInterrupt event will be generated when a hardware interrupt occurs, and sets the Masked property (see below) to False. procedure MaskInterrupt; ------------------------ Masks the hardware interrupt specified by the IRQNumber property. procedure DestroyIRQ; --------------------- Frees the memory and code previously assigned for unmasking the hardware interrupt specified by the IRQNumber property, setting the IsIRQSet property to False and the Masked property to True. property IsIRQSet: Boolean; (read only); ---------------------------------------- Read-only property which specifies whether the hardware interrupt handler has been created by the SetIRQ method. property Masked: Boolean; (read only); -------------------------------------- Read-only property which specifies whether the hardware interrupt handler has been removed (True), or is still active (False). property IRQCounter: dWord; (read only); ---------------------------------------- Read-only property which counts the number of hardware interrupts intercepted by the TVicHW32 kernel-mode driver. The IRQCounter property is provided largely for debugging purposes, allowing you to compare the actual number of hardware interrupts generated with the number processed by your application. procedure SimulateHwInt; ------------------------ This procedure is provided for purposes of debugging, and allows you to simulate a hardware interrupt. When this procedure is called, the TVicHW32 kernel-mode driver will feign a "hardware interrupt", without directly affecting the hardware. 8. CONTACT INFORMATION ====================== Comments, questions and suggestions regarding TVicHW32 can be directed by e-mail to victor@ivi.ugatu.ac.ru or tools@entechtaiwan.com. With best wishes, Victor Ishikeev March 1997